home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -in_the_mag- / multitasking / coders / ppipc / ipc_include / ipc.h < prev    next >
C/C++ Source or Header  |  2000-03-05  |  12KB  |  313 lines
  1. /*******************************************************************
  2.  *                                                                 *
  3.  *                           IPC.h                                 *
  4.  *                                                                 *
  5.  *           Inter-Process-Communication Message Format            *
  6.  *                                                                 *
  7.  *              Revision 2.21 -- 1989 April 28                     *
  8.  *                                                                 *
  9.  *         Copyright 1988,1989 Peter da Silva & Peter Goodeve      *
  10.  *                      All Rights reserved                        *
  11.  *                                                                 *
  12.  *  This source is freely distributable, but should not be         *
  13.  *  modified without prior consultation with the authors.          *
  14.  *                                                                 *
  15.  *******************************************************************/
  16. /*******************************************************************
  17.  *                                                                 *
  18.  *  89:3:26 [2.1]   Shared Library Version -- LoadIPCPort added.   *
  19.  *  89:4:17 [2.2]   MakeIPCId and FindIPCItem added;               *
  20.  *     "      "     Flags IPC_NONSTANDARD and IPC_VITAL added.     *
  21.  *  89:4:28 [2.21]  IPC_NOTKNOWN changed to IPC_REJECT             *
  22.  *                                                                 *
  23.  *******************************************************************/
  24.  
  25. #ifdef AZTEC_C
  26. /* can't use prototyping */
  27. #define NARGS 1
  28. /* (if NARGS is undefined, prototyping is enabled) */
  29. #endif
  30.  
  31. #ifndef EXEC_TYPES_H
  32. #include "exec/types.h"
  33. #endif
  34.  
  35. #ifndef EXEC_PORTS_H
  36. #include "exec/ports.h"
  37. #endif
  38.  
  39. /*** Item Reference block -- an arbitrary number of these may be
  40.    put in an IPCMessage ***/
  41.  
  42. struct IPCItem {
  43.     ULONG   ii_Id;      /* four character ID (normally);
  44.                            determines exact meaning of IPCItem IDs */
  45.     ULONG   ii_Flags;   /* upper 16 bits have standard meaning;
  46.                            lower 16 bits are message dependent */
  47.     ULONG   ii_Size;    /* size of data structure (zero if ii_Ptr is not
  48.                            actually a pointer to data) */
  49.     void   *ii_Ptr;     /* points to defined data structure (could be within
  50.                            message block if IE_Flags says so) -- also may be
  51.                            recast to other 32-bit value (e.g. Lock) */
  52.     };
  53.  
  54.  
  55.  
  56. /*** The basic IPCMessage block ***/
  57.  
  58. struct IPCMessage {
  59.     struct Message  ipc_Msg;
  60.         /* ..ln_Name field should be NULL
  61.             mn_Length will include IPC_Items array and any in-line data
  62.         */
  63.     ULONG   ipc_Id,                /* four character (or other) ID */
  64.             ipc_Flags;
  65.     UWORD   ipc_ItemCount;         /* number of items in array */
  66.     struct  IPCItem ipc_Items[1];  /* .. actual size as needed */
  67.     };
  68.  
  69.  
  70. /*************************************************************/
  71.  
  72. /*** Note that ALL bits in the upper byte are now allocated 89:4:17 ***/
  73. /*** These are now considered pretty well set in concrete!  ***/
  74.  
  75. /* Flags set by client: */
  76. /* -- may appear in either IPCItem or IPCMessage Flags field */
  77.  
  78. #define IPC_TRANSFER   0x08000000
  79.     /* Data block ownership is to be transferred to receiver. */
  80. #define IPC_NETWORK    0x04000000
  81.     /* The data in this block/message may be transmitted to
  82.        another machine */
  83. #define IPC_INMESSAGE  0x02000000
  84.     /* The data in this block/message is included in the message length */
  85. #define IPC_NONSTANDARD 0x01000000
  86.     /* The data in this block/message does NOT conform to the protocol
  87.        (might be a list structure, for instance).  DON'T delete or modify
  88.        UNLESS you know how to handle it.
  89.        NOTE: ANY ID used with this flag MUST have common meaning to ALL
  90.        programs (if they recognize it). */
  91.  
  92. #define IPC_VITAL      0x20000000
  93.     /* This Item/Message MUST be recognized, otherwise the whole message
  94.        must be replied unprocessed (with IPC_REJECT set). */
  95.  
  96.  
  97. /* Flags returned by server: */
  98.  
  99. #define IPC_REJECT     0x80000000
  100. #define IPC_NOTKNOWN   0x80000000
  101.     /* The server could not handle this block/message
  102.        (either because it did not understand the ID or
  103.        was unable to process it -- see the secondary flags) */
  104.     /* IPC_REJECT replaces IPC_NOTKNOWN (which should no longer be used) */
  105.  
  106. #define IPC_MODIFIED   0x40000000
  107.     /* The server modified the data, either within the
  108.        supplied data block(s) or -- if permitted -- by
  109.        replacing/removing the block pointer; again maybe
  110.        other flag bits should indicate the nature of
  111.        the modification */
  112.  
  113. /* valid for Item only: */
  114. #define IPC_SERVER_OWNED 0x10000000
  115.     /* The server owns this data Item -- either because it has
  116.        created it or because it took it over from the client
  117.        (in which case it clears IPC_TRANSFER, which must have
  118.        been set) */
  119.  
  120.  
  121. /* secondary flag bits: */
  122.  
  123. #define IPC_CHECKITEM 0x00800000
  124.     /* associated with IPC_REJECT -- indicates that one or more
  125.        particular items caused the flag to be set */
  126. #define IPC_FAILED 0x00400000
  127.     /* IPC_REJECT flag was set because the server failed to
  128.        handle an ID that it is designed to (rather than just
  129.        not recognizing the block) */
  130.  
  131. /*************************************************************/
  132.  
  133.  
  134. /*** IPC Ports and Procedures ***/
  135.  
  136.  
  137. /* -- see IPCPorts.h for actual structure definitions */
  138. #ifndef IPC_PORTS_H
  139. /* Normal user doesn't need access to port components,
  140.    so just use a convenient define.  Note that an IPC port
  141.    is NEVER in private data space -- or in the public port
  142.    list -- it is created and managed by the package routines
  143.    only.
  144.    NOTE also: IPCPorts are READ-ONLY TO ALL APPLICATION PROGRAMS!!
  145.    -- their internal data must be changed ONLY by the library routines;
  146.    for example, their ln_Node must NEVER be used by an application
  147.    to hang them on a local list (even if they are anonymous). */
  148. #define IPCPort MsgPort
  149. #endif
  150.  
  151. /*************************************************************/
  152.  
  153.  
  154. /* IPC Port Handling function prototypes: */
  155.  
  156. #ifndef NARGS /* define this to SUPPRESS function argument prototyping */
  157.  
  158. struct IPCPort * LoadIPCPort(char *);
  159.     /* [Requires an external "Port Broker" process -- otherwise
  160.        it behaves like FindIPCPort.]
  161.        returns pointer to port if it exists and has a Server
  162.        (or one is loading) -- if it doesn't, it sends a
  163.        message to PortBrokerPort requesting a server for the
  164.        port; if the Broker process cannot load a server (or
  165.        there IS no Broker process) the function returns
  166.        NULL; if the Broker initiates execution of a server
  167.        the function returns the port pointer and registers a
  168.        new connection to the port */
  169.  
  170.                             /* * * * */
  171.  
  172. ULONG MakeIPCId(char *);
  173.     /* returns 32-bit ID value corresponding to supplied (4-char) string
  174.        (shorter will be LEFT justified, longer will be truncated). */
  175.  
  176. struct IPCItem * FindIPCItem(struct IPCMessage *, ULONG, struct IPCItem *);
  177.     /* returns first item in message that matches ID; if item pointer is
  178.        not NULL, search will begin at that item rather than first. */
  179.  
  180.                             /* * * * */
  181.  
  182. struct IPCPort * FindIPCPort(char *);
  183.     /* returns pointer to port if it exists -- null otherwise;
  184.        registers a new connection to the port */
  185.  
  186. struct IPCPort * GetIPCPort(char *);
  187.     /* returns pointer to port -- it is created if it doesn't exist;
  188.        registers a new connection to the port */
  189.  
  190.  
  191. void UseIPCPort(struct IPCPort *);
  192.     /* adds a connection to a port (passed by pointer from another
  193.        process) */
  194.  
  195.  
  196. void DropIPCPort(struct IPCPort *);
  197.     /* disconnect from port -- port will be destroyed if there are
  198.        no other connections left */
  199.  
  200.  
  201. struct IPCPort * ServeIPCPort(char *);
  202.     /* become a server for the named port (created if it doesn't exist);
  203.        null is returned if the port already has a server, otherwise a
  204.        pointer to it is returned */
  205.  
  206. void ShutIPCPort(struct IPCPort *);
  207.     /* (server only) prevent more messages being sent to this port, but
  208.        do not end server connection; remaining messages can be dealt
  209.        with before Leaving */
  210.  
  211. void LeaveIPCPort(struct IPCPort *);
  212.     /* cease to be a server for this port; another process can then
  213.        become a server if it desires */
  214.  
  215. CheckIPCPort(struct IPCPort *, UWORD);
  216.     /* returns number of current connections to this port (including
  217.        server); a call by the server (only) will also set the (user
  218.        settable) port flags to the value in the second argument --
  219.        currently the only valid flag is IPP_NOTIFY */
  220.  
  221.  
  222. PutIPCMsg(struct IPCPort *, struct IPCMessage *);
  223.     /* sends an IPCMessage to an IPCPort; if the port has no server or
  224.        is shut, the message is not sent and the function returns FALSE;
  225.        otherwise it returns TRUE. (Other port flags to be added later
  226.        may affect these actions.) */
  227.  
  228. struct IPCMessage * CreateIPCMsg(int, int, struct MsgPort *);
  229.     /* creates a standard IPCMessage block (in MEMF_PUBLIC) with the
  230.        number of IPCItems supplied as first argument;  the second
  231.        argument is the number of bytes -- if any -- to reserve beyond
  232.        that required for the items; the third is a pointer to the
  233.        ReplyPort (may be NULL -- note that it's a standard MsgPort,
  234.        not an IPCPort). (You always have to manage any data
  235.        blocks yourself). */
  236.  
  237.  
  238. void DeleteIPCMsg(struct IPCMessage *);
  239.     /* deletes a standard IPCMessage block;  you must first have disposed
  240.        of any attached data as appropriate */
  241.  
  242. /*************************************************************/
  243. #else NARGS defined
  244.  
  245. struct IPCPort * LoadIPCPort ();
  246.  
  247. ULONG  MakeIPCId ();
  248. struct IPCItem * FindIPCItem();
  249.  
  250. struct IPCPort * FindIPCPort ();
  251. struct IPCPort * GetIPCPort ();
  252. void             UseIPCPort ();
  253. void             DropIPCPort ();
  254. struct IPCPort * ServeIPCPort ();
  255. void             ShutIPCPort ();
  256. void             LeaveIPCPort ();
  257. int              CheckIPCPort ();
  258. int              PutIPCMsg ();
  259. struct IPCMessage * CreateIPCMsg ();
  260. void             DeleteIPCMsg ();
  261.  
  262. /*************************************************************/
  263. #endif NARGS
  264.  
  265.  
  266. /* System IPCPort flags: */
  267.  
  268. #define IPP_SERVED 0x8000
  269.     /* port currently has a server */
  270. #define IPP_SHUT 0x4000
  271.     /* port is no longer open for new messages (server still attached) */
  272. #define IPP_REOPEN 0x2000
  273.     /* set (by "Port Broker") to request that server reopen service
  274.        to this port after it has completed Shut/Leave sequence
  275.        in progress */
  276. #define IPP_LOADING 0x1000
  277.     /* set (by "Port Broker") to indicate that a server is being loaded
  278.        for this port (cleared by ServeIPCPort()) */
  279.  
  280.  
  281. /* Server settable Port flags: */
  282.  
  283. #define IPP_NOTIFY 0x0001
  284.     /* server wants to be signalled if connection is added or
  285.        dropped (the port sigbit is used to signal the task,
  286.        but no message is sent) */
  287.  
  288. /*************************************************************/
  289.  
  290. /*
  291.  *  Some useful Macros:
  292.  */
  293.  
  294. #define GetIPCMessage(port) ((struct IPCMessage *)GetMsg((struct MsgPort *)port))
  295.  
  296. #define ReplyIPCMessage(msg)  ReplyMsg((struct Message *)msg)
  297.  
  298. #define SigBitIPCPort(port) (1<<((struct MsgPort *)port)->mp_SigBit)
  299.     /* note: this will work whether or not IPCPorts.h has been included */
  300.  
  301.  
  302. /*
  303.    For convenience in creating (fixed) IDs:
  304.     (Alternatively, your compiler may have multi-character constants,
  305.      which you may find more convenient (but less portable...))
  306.      The library now also supplies the function MakeIPCId which you can
  307.      use to create IDs at run-time from strings.
  308. */
  309.  
  310. #define MAKE_ID(a,b,c,d) ((a)<<24L | (b)<<16L | (c)<<8 | (d))
  311.  
  312.  
  313.